
===== Overview configureMosaic =====

configureMosaic is a command-line tool to query and configure Mosaic and SLI
Mosaic.

It's designed to be usable from a script, so every command takes all of its
arguments on the command line. The output of each command is written as XML to
standard out.

Currently, configureMosaic is only supported on Windows-7, Windows-8 & Windows-10.

configureMosaic will indicate simple success or failure with its exit status:
	0 -- Success.
	1 -- Success, but with warnings.
	2 -- The command or parameters are invalid.

Any other value indicates an error.

===== System Requirements =====

configureMosaic is a 32-bit application that will work for both 32 and 64 bit versions of Windows-7, Windows-8 & Windows-10 

configureMosaic requires the Microsoft Visual C++ 2008 Redistributable Package to operate. 
Most workstations will have this installed already. If you get an error about the side by side 
configuration being incorrect or missing libraries install the Package from Microsoft:
http://www.microsoft.com/download/en/details.aspx?id=5582

Administrator privileges are required for most of the configureMosaic commands. 

===== Configuring Mosaic =====

To change the current Mosaic topology, use the "test" and "set" commands to
specify one or more display grids:

	configureMosaic.exe <set|test> rows=NUM_ROWS cols=NUM_COLUMNS [passivestereo] [options...]

The "set" command will apply one or more display grids. The list is exhaustive,
so any display not given in one of the grids will be deactivated. The first
grid will become the GDI primary, and any additional grids are arranged
left-to-right after it.

The "test" command will print the grids that it would set, but won't change
anything. It will also verify that the grids are all valid, and will print the
list of available resolutions for each grid.

If the grids are not valid, then the "test" command will display the grids
along with whatever errors it found, and exit with a status of 1.

The "rows" and "cols" options specify the number of rows and columns in the
grid. If the "passivestereo" option is given, then the grid will use passive
stereo. To use a single display instead of a Mosaic topology, specify a grid
with only one row and one column.

To specify more than one grid, separate each grid with the option "nextgrid":

	configureMosaic.exe set rows=NUM_ROWS columns=NUM_COLUMNS nextgrid rows=...

To set the resolution of the grid, use the "res" option. To set the overlap
or bezel correction, use the "overlap", "overlapcol", and "overlaprow" options,
or the "bezel", "bezelcol", and "bezelrow" options:

	res=WIDTH,HEIGHT,REFRESH_RATE
	overlap=COL,ROW
	overlapcol=OVERLAP[,OVERLAP...]
	overlaprow=OVERLAP[,OVERLAP...]
	OR
    bezel=COL,ROW
	bezelcol=BEZEL[,BEZEL...]
	bezelrow=BEZEL[,BEZEL...]

The "res" option specifies the resolution and refresh rate of each display. If
not specified, it will default to the highest available resolution. 

The "overlapcol" and "overlaprow" options specify the overlap between each column and each row. 
You can specify a different overlap value for each row and column. 
Any overlaps that you do not specify will be zero.

If you don't need different overlaps for each row and column, you can instead
use the "overlap" option to specify a per-row and per-column overlap that
applies to the entire grid.

Bezel correction is equivalent to negative overlap. The "bezel", "bezelcol",
and "bezelrow" options are equivalent to specifying a negative number to the 
"overlap", "overlapcol", and "overlaprow" options, respectively.

By default, configureMosaic will try to figure out which displays to assign to
each grid. To specify a layout, use either the "out" or "display" options:

	out=GPU_INDEX,OUTPUT_INDEX
	display=DISPLAY_ID

The "out" specifies a display by physical GPU and output index, and the
"display" option specifies a display by its display ID. Use the "query" command
to determine the available GPU's and displays.

The displays are given in row-major order. A 2-row, 3-column grid, for example,
would lay out its six displays in this order:

	0 1 2
	3 4 5

If the "passivestereo" option is given, then the grid will use passive stereo. 
In fact the grid will clone itself to 2 grids.
Along with â€˜Stereo Enableâ€™ set to â€˜Onâ€™ and â€˜Stereo â€“ Display modeâ€™ selected for â€˜nView Clone modeâ€™ 
on the NVIDIA control panelâ€™s â€˜Manage 3D settingsâ€™ page; left and right stereo eyes will be visible on different grids.

For passive stereo mode, a 2-row, 2-column grid with passive stereo would
lay out its displays in the following order:

	Left eye:
	0 1
	2 3

	Right eye:
	4 5
	6 7

To program passive stereo using configureMosaic, there are 2 pre-requisites
1. The corresponding left & right eyes need to be connected on the same GPU.
   i.e. (0 & 4) have to be on the same GPU, similarly (3 & 7), (1 & 5) and (2 & 6) need to be on the same GPUs too.
2. For the <out=GPU_INDEX,OUTPUT_INDEX>, the left eye should be followed by its corresponding right eye.
   i.e. out=gpu0,leftEye(0) out=gpu0,rightEye(4) out=gpu0,leftEye(1) out=gpu0,rightEye(5) out=gpu1,lefteye(2)...

For the above mentioned passive stereo scenario lets consider the following setup of 2x Quadro boards with 4 DP outs each, 
with the following connections to satisfy our pre-requisite 1:
GPU 0 connected with displays 0,1,4,5
GPU 1 connected with displays 2,3,6,7

	configureMosaic.exe set rows=2 cols=2 passivestereo out=0,0 out=0,4 out=0,1 out=0,5 out=1,2 out=1,6 out=1,3 out=1,7
   
Note that configureMosaic doesn't support a partial list of displays. If you
specify any display, then you must specify the entire layout for every grid.


===== Querying Mosaic =====

Use the "query" command to find the list of available GPU's and displays, and
the current set of grids:

	configureMosaic.exe query [gpu] [lgpu] [current] [all]

The "gpu" option will print the list of physical GPU's, and the displays
attached to each GPU. Use this command to determine the indices or ID's of the
displays to use for the "set" command.

The "lgpu" option will print a list of available logical GPU's. Each logical
GPU will have a list of supported features and a list of one or more physical
GPUs.

The "current" command will print the current display grids.

The "all" command is equivalent to specifying "gpu", "lgpu", and "current".


===== Other commands =====

The "disable" command will disable Mosaic and return to a single display. It's
equivalent to using the "set" command to apply a single 1x1 grid. It will use
the first display of whichever grid is the GDI primary.

Use the "gridPos" argument to specify the coordinates of the upper left corner
of a grid when using multiple grids.

Use the "maxperf" argument to create an SLI topology using the largest valid
GPU grouping on the system - this is the same as the 'Maximum GPU Topology' 
setting in the Nvidia Control Panel.

The "qsyncslave" argument can be used to set the framelock setting for the
Mosaic to be the timing client.

The "listconfigcmd" command will output the appropriate commandline arguments
for the current mosaic configuration.

Additionally, the "help" command will display a list of available commands and options.
